Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 014 / nusq110.arc / NUSQ110.DOC < prev

Wrap

Text File | 1984-10-21 | 19.0 KB | 491 lines

NUSQ - File unsqueeze utility Documentation for CP/M-86 and MS-DOS versions 1.11 (CP/M-86), 1.10 & 1.10D (MS-DOS) Cliff Sharp October 21, 1984 DOCUMENTATION TOPICS OVERVIEW IN CASE OF TROUBLE COMMAND MODE PROGRAM MESSAGES INTERACTIVE MODE ANNOUNCEMENT INSTALLATION HISTORY OVERVIEW NUSQ is a utility for expanding squeezed files to their original uncompressed state. Two separate versions of NUSQ are available, one for CP/M-86 and one for the MS-DOS operating system. NUSQ has two operating modes. In the command mode, a single instruction to NUSQ is passed from the command line which invokes NUSQ. The command mode requires less effort to use when you have only one file to unsqueeze, or when the names of the files you wish to unsqueeze can all be specified by one "wildcard" name. However, when you have more than one file to unsqueeze and a "wildcard" won't do the job right, or when the files you want to unsqueeze are on more than one disk, the interactive mode allows you to specify only those files which you want processed, without reloading the program every time. In the interactive mode, NUSQ executes one command, then waits for another. MS-DOS versions of NUSQ including and subsequent to 1.10 can use date and time information encoded in files squeezed with NSQ. This means that a file squeezed with NSQ, 'modemed' to another location, and unsqueezed with NUSQ (version 1.10D or greater) will retain the date and time of ORIGIN instead of DESTINATION. NSQ encodes this information at the END of the squeezed file, so such files retain compatibility with earlier unsqueeze programs. See the installation section of this document for details on how to implement this feature in NUSQ. Any files squeezed with NSQ (versions 2.01 or higher) will have the necessary date and time information encoded in them. COMMAND MODE To unsqueeze only one file, the command mode invocation A>nusq nerts.aqm will unsqueeze the file NERTS.AQM. You don't need to specify the name of the output file (in fact, you can't); the name was stored within the file at the time it was squeezed, and that name will be used to create the new file. (If you want to name it differently after you have unsqueezed it, use the REName command when NUSQ is finished.) You can unsqueeze all squeezed files on a single disk by issuing the command A>nusq *.?q? Theoretically at least, all file squeezers create an output file whose name is the same as that of the original file, except that the filename extension field is modified by changing the middle letter to a "Q". (If a file has no filetype, a 'QQQ' is appended for the file type for the encoded file. When a file has been renamed after being squeezed, this might not be the case; hopefully, the person who renamed it remembered the "Q".) The "wildcard" file specification shown above tells NUSQ to unsqueeze any file it finds (on the default disk) which has a "Q" in the filename extension; that should get NUSQ to unsqueeze every squeezed file on the disk. NUSQ will display the name of each file it finds, and the name of the output file it produces, as it proceeds: NERTS.AQM -> NERTS.ASM ORGPLOTZ.DQC -> ORGPLOTZ.DOC Because NUSQ checks the first two bytes of each input file for a valid Squeeze Signature (0FF76 hex), it is possible to say: nusq *.* and get the same results as with "nusq *.?q?". It is faster, however, to use the *.?q? method, as that will preclude a lot of unnecessary file openings. NUSQ will also accept more than one filename on the command line: A>nusq nerts.aqm orgplotz.dqc frop.cq To use a different disk for output than for input, end the command line with just the drive designation. Example: A>nusq giggle.tqt b: will write the output file (ostensibly GIGGLE.TXT) on drive B:. You will find that NUSQ is very forgiving, as: A>nusq b: giggle.tqt will accomplish the same thing. (Note the space between 'b:' and 'giggle'!) INTERACTIVE MODE Let's suppose now that you have a large number of squeezed files on your disk, and you only want to unsqueeze some of them. Unless you can specify only those files by using a "wildcard" name, you'll probably find it easier to achieve your goal by using the interactive mode of NUSQ. Another instance where it would be easier to use interactive mode is one where the files you wish to unsqueeze are on more than one disk, in more than one drive. The command A>nusq displays the startup message, then prompts for command input with an asterisk ("*"). NUSQ Version x.xx Dave Rand, Paul Homchick and Cliff Sharp xx/xx/xx Use: NUSQ afn [afn afn ...] [destination drive:] *_ (The underline shows the cursor position; my name appears only in the MS-DOS version.) At the asterisk, you type a filename ("wildcards" are allowed here, too). NUSQ will unsqueeze the file, then print the asterisk prompt again and wait for more commands. When you're finished and want to exit NUSQ, a blank line or ^C will return you to the operating system. As distributed, NUSQ won't write over an existing file without the user confirming the operation. Something very like the following will happen: A>nusq foo.bqr nusq: FOO.BQR -> FOO.BAR already exists, Overwrite <Y>es, <N>o? overwriting... In this case the user answered "Y" at the question mark, and NUSQ went ahead with the operation. If "N" is the response, the unsqueeze operation is aborted, and the program goes on to the next item in the list (or exits, if the list is empty). INSTALLATION Two user-configurable options are provided: Confirm Before Over- write, and Select Date Option. As distributed, NUSQ v1.04 will ask for confirmation before overwriting a file, and will use the current date and time when creating the output file. If you would rather have NUSQ write over existing files with wanton abandon, without pausing and asking for confirmation, use DEBUG.COM to patch location 0103H to be 00H instead of 0FFH. An example of this patch: A>debug b:nusq.com -e103 xxxx:0103 FF.00 -w Writing YYYY bytes -q A> Select Date Option allows you four choices for the way the output file is dated. As distributed, NUSQ will date the output file in the same manner as most other programs do, i.e. the date and time shown in directory displays will be the date and time at which you unsqueezed the file. You may change this option by changing the byte at location 0104H (which you can do by using the instructions above and the values you will see in a moment, using the instructions shown above but substituting 104 for 103 wherever 103 appears). Copies of NUSQ patched in this manner will display a 'D' after the version number, signifying that the input file date option has been enabled, i.e. "1.10D". The available options are: 0) Leave it to DOS 1) Output file gets the same date/time as the input file 2) If the squeezed file contains the special date/time signature inserted by NSQ at squeeze time, use the date/time contained in that signature: otherwise, use the current date/time 3) If the squeezed file contains the special date/time signature inserted by NSQ at squeeze time, use the date/time contained in that signature: otherwise, use the same date/time as the input file If you would like the unsqueezed file to retain the same date and time shown for the input file (option 1), patch 0104H to 0FH. For option 2, patch 0104H to 0F0H; for option 3, patch 0104H to 0FFH. Following is a table that trys to explain these options: option value use current use input file use encoded 0. 00 yes - - 1. 0F - yes - 2. F0 - - yes 3. FF - do this second try this first There is a reason for our distributing NUSQ with the date/time options disabled. If you have a backup utility (usually this applies to a "hard" disk) that uses the file date and time to determine whether or not a file should be backed up, it is possible that using the input file date could cause loss of a file by having an 'old' date on a 'new' file, and losing a backup. If you are unsure whether this applies to you, leave the date/time options unchanged until you can find out. IN CASE OF TROUBLE First, no matter HOW sure you are that you're doing things correctly, try another method of using NUSQ. If you tried com- mand mode without luck, try the interactive mode; if you were in the interactive mode when it bombed, try command mode. Make sure you try at least one command that is just like one shown in this document (but, of course, use the name of your file instead of NERTS or ORGPLOTZ) before you conclude that things are awry. Occasionally, for one reason or another, it's possible to get a bad copy of a program or file; transmission errors and disk errors have been known to cause many problems. (If you can successfully unsqueeze at least one squeezed file, you probably have a good copy of the program; if so, your copy of the file you're trying to unsqueeze may be the culprit.) The best way to tell if this is the case is to use a utility like CRCK on the original copy of the offending file/program, and on your copy; if the numbers you get don't match, you most likely have a bad copy of the file/program you checked and should obtain another copy of it. (Check the new copy, too, when you get it.) This may sound silly, but do you have the correct version for your operating system? If you try to run the CP/M-86 version under MS-DOS, strange things may happen; same for the MS-DOS version under CP/M-86. Also, try using TYPE to actually type the executable file on your screen; you'll most likely see the author's name. (See the history later in this document to see who wrote what.) If all that checks out, the logical next step is to compare notes with someone locally to see if anyone else is experiencing problems. The system operator ("sysop") of the system from which you obtained the software can usually be of help if you tell him which version you're using (CP/M-86 or MS-DOS) and the name of the file you're trying unsuccessfully to unsqueeze. Alternative- ly, you can leave a message addressed to "ALL" on a local bulletin board; usually some helpful person will jump in with suggestions. Remember, there are no silly questions, only silly mistakes. If you've tried all this, and you're still sure you have a problem, then it's last-resort time. Contact the author of your version of the program. His name, and a way to contact him, is in the very beginning of the NUSQ.COM file; TYPE NUSQ.COM and you should see it. (If that doesn't work, use DDT, SID or DEBUG.) This is by far the slowest method of resolving problems, and people who contact program authors with problems caused by oper- ator error are usually looked upon unfavorably, so do this only if all else fails. Be sure to include the name of the system where you got your copy of the program, the name of the file you're trying to unsqueeze and the place where you got the file, and a description of what went wrong. It might also be nice to know the names of any people who have tried to help you with your problem so far. PROGRAM MESSAGES Output drive = x: You selected a disk drive different from the one containing the original file for the output file to be created on. No file(s) found. No files meeting the filename specification you gave were found on the disk you indicated they would be on. Try reentering the file specification, or check to make sure you are specifying the correct drive and/or disk. Also, if you are using wildcard characters ('*', '?') in the specification, make sure the usage is correct. Out of memory. Use more specific filenames. NUSQ is operating in a small workspace, and the wildcard file specification you gave has found a large number of files. The storage for all these filenames has eaten away so much workspace that NUSQ has no room left in which to unsqueeze any of the files. Give NUSQ a filename specification which will find a smaller number of files, so that more unsqueezing workspace is available. (Users with 96K or more memory will probably never see this message.) xxxxxxxx.xxx is not a squeezed file. Squeezed files are marked with a particular "signature": (FF76), NUSQ did not find this signature. Either the beginning of this file has been damaged, somebody is being cute and is trying to invent new "standards", or this file is really not a squeezed file. xxxxxxxx.xxx already exists, Overwrite <Y>es, <N>o? A file already exists which has the same name as that given in the squeezed file for creating the output file. A 'Y' response will cause NUSQ to overwrite the existing file; a 'N' answer will cause NUSQ not to unsqueeze this file. If you want to unsqueeze this file without destroying the old, existing file, rename the existing file before running NUSQ again. This message will not appear if NUSQ was modified to overwrite with wanton abandon (see DEBUG instructions preceding). Cannot create output file. Aborting. Either this disk has so many files on it that there is no room left for a new directory entry, or (with MS-DOS 2.x versions) a subdirectory exists with the same name that NUSQ must use for the output file. In any event, you will probably need to use a different disk for the output file. (See the preceding instructions.) File has illegal decode size. Aborting. Something is wrong with the input file; either it is not really a squeezed file, or it has been modified or damaged, or (less likely) the squeezer which created it did something wrong. This file cannot be unsqueezed; try a new copy. Close failed... NUSQ was unable to close the output file. This is a VERY unlikely error, and may mean either that your copy of NUSQ is damaged or the copy of the operating system currently in memory has been corrupted somehow. Try booting from a different disk, or try another copy of NUSQ. If these fail, contact the author. ERROR - Checksums don't match in file xxxxxxxx.xxx Something is wrong with the input file; either it has been modified or damaged, or (less likely) the squeezer which created it did something wrong. This file cannot be unsqueezed; try a new copy. Disk full. Aborting and deleting output file. The disk on which the output file is being written has become full; there is no more disk space to contain the remainder of the file. Create the output file on a different disk. Premature EOF on file... aborted. NUSQ has not found the special end-of-file (EOF) mark which is present in every squeezed file. Most likely, the last part of this file is missing. This file cannot be unsqueezed. ANNOUNCEMENT A look at the signon message in interactive mode will reveal that NUSQ is the result of committee action. Said committee was unable to agree on whether the source code should be distributed as public domain code; consequently, source code is not available. HISTORY NUSQ is a file unsqueezer utility written entirely in assem- bly language. The first file squeezer and unsqueezer in the public domain were written by Richard Greenlaw, in the C program- ming language. A Z80 assembly language version was done by Gail Zacharias at MIT in the Spring of 1983. In late '83 Dave Rand wrote an 8080 version, which went through several versions, culminating in USQ120.COM. Paul Homchick assumed the task of converting Dave's efforts to 8086/8088 assembly language for execution under CP/M-86 in early 1984, and I converted Paul's version to run under MS-DOS a bit later. CP/M VERSIONS 1.08 January 28, 1984. First released version uploaded to Compuserve. 1.09c March 24, 1984. Carriage Return on empty line exits program. Optimized tree-walker adapted from MS-DOS version resulting in 15% speed increase. 1.10 June 22, 1984. Prior tree-walker was not as optimized as we thought. Further optimi- zation borrowed from MS-DOS version, result- ing in another 25% increase in speed. 1.11 October 15, 1984. Version 1.10 introduced a bug that would cause a 'Premature EOF' message to be displayed if a legitimate squeezed file used every byte in the last sector. Now fixed. MS-DOS VERSIONS 1.00M March 21, 1984. Original version uploaded to Compuserve. Had serious bug that sometimes resulted in short files with no warning. 1.01M March 31, 1984. Carriage return on empty line at Command prompt ("*"), now returns to DOS instead of giving another prompt line. Short File BUG still in this version! 1.02M April 12, 1984. Fixed Random Block Write DOS calls. Files now unsqueeze to exact length, instead of 128-byte multiples as in prior versions. Buffer flush code fixed to elim- inate short file bug. 1.03 and 1.03D June 22, 1984. Decode routines re- written for a 30-percent increase in speed. Version 1.03D uses date and time of the input file when creating output file; 1.03 does not do so. This date feature can be user config- ured by changing a byte at offset +4 in the .com file. See 'Installation,' above, for details. Versions prior to this one always appended a 1A hex to the end of the unsqueezed file. This CP/M anachronism has been removed in this version. 1.04 and 1.04D September 1, 1984. Filename parsing routine changed to use MS-DOS "parse" func- tion call. Prompt "No directory space" which used to appear when a file create function failed changed to read "Cannot create output file", because MS-DOS 2.xx and later will reject the create request if a directory by the same name exists. 1.10 and 1.10D October 21, 1984. "Bug" fixed; squeezed files which were 100% utilized (i.e.,every last byte had significant data), and which were a multiple of 128 in length, would give a "Premature EOF" error. Added date/time handling for NSQ-created files. Also changed input file handling to handle file lengths more accurately. CP/M and CP/M-86 are trademarks of Digital Research, Inc. MS (as in MS-DOS) is a trademark of Microsoft, Inc.